<?php
/**
 * 
 * This interface allows for adapter extension
 * intended to paralell PDO but not be dependent on PDO
 * 
 * @author Alton Crossley <crossleyframework@nogahidebootstrap.com>
 * @package Crossley Framework
 *  
 * @copyright Copyright (c) 2003-2009, Nogaide BootStrap INC. All rights reserved.
 * @license BSD http://opensource.org/licenses/bsd-license.php
 * @version $Id:$
 * 
 */
/**
 * data adapter
 * 
 * Always uses prepared statemetns
 *
 */
interface X_Data_Adapter_Interface
{
    /**
     * set the query to be used in the prepared statemnet with bind params
     * ex: INSERT INTO REGISTRY (name, value) VALUES (:name, :value)
     * ex: SELECT * FROM REGISTRY WHERE name = :name
     * ex: SELECT * FROM REGISTRY WHERE name LIKE :name
     * 
     * @param unknown_type $sString
     */
    public function setQuery($sString);
    
    /**
     * set an array of bind parameters
     * bind array is in token => value pairs
     * 
     * set $bReset to true if you want to only bind this array
     *
     * @param array $aBindArray
     * @param bool $bReset
     */
    public function bindArray(Array $aBindArray, $bReset);
    
    /**
     * limit the rows returned
     *
     * @param int $iStart
     * @param int $iCount
     */
    public function limit($iStart, $iCount);
    
    /**
     * Prepares a statement for execution
     * 
     * @param string $sStatement
     * @param array $aDriverOptions
     */
    public function prepare($sStatement, $aDriverOptions = array());
    
    /**
     * Executes an SQL statement
     * 
     * @param string $sStatement
     */
    public function query($sStatement = null);
    
    /**
     * bind the parameter token to the given value 
     *
     * @param string $sTokenName
     * @param string $sValue
     */
    public function bind($sTokenName, $sValue);
    
    /**
     * returns the names of the bind tokens in the query
     *
     * @return array
     */
    public function getBindTokens();
        
    /**
     * binds and executes the statement
     *
     */
    public function execute();
        
    /**
     * set the type of data that is returned from next()
     *
     * @param PDO_FETCH $iMode PDO compatible fetch mode
     * @param unknown_type $xParam1 matching pdo parameter
     * @param unknown_type $xParam2 matching pdo parameter
     * @return bool true if accepted by the adapter
     */
    public function setReturnMode($iMode, $xParam1 = null, $xParam2 = null);
    
    /**
     * count the rows affected by a update type query
     *
     */
    public function countAlteredRows();
    /**
     * count the resulting rows
     *
     */
    public function countRetrievedRows();
    
    /**
     * get the last autonum id from the last inserted row
     *
     */
    public function getLastInsertId($sName = null);
    
    /**
     * return the result set in a 2D array
     *
     */
    public function getResult($sIndexName);
    /**
     * return the result set in a 2D associative array
     *
     * @param string $sIndexName name of value to use as associative index
     */
    public function getResultAssoc($sIndexName);
    /**
     * return a result set as an array of the given class
     * attributes matching the column names will be set to the 
     * values for the row it represents
     *
     * @param unknown_type $sClassName
     * @param unknown_type $sIndexName
     */
    public function getResultObjectArray($sClassName, $sIndexName);
    
    /**
     * start a transaction
     *
     */
    public function beginTransaction();
    /**
     * commit a transaction
     *
     */
    public function commit();
    /**
     * roll back a transaction
     *
     */
    public function rollBack();
}